home *** CD-ROM | disk | FTP | other *** search
- ELF_BEGIN(3E) Last changed: 4-12-99
-
-
- NNAAMMEE
- eellff__bbeeggiinn - Make a file descriptor
-
- SSYYNNOOPPSSIISS
- cccc [_f_l_a_g ...] _f_i_l_e ... --lleellff [_l_i_b_r_a_r_y ...]
-
- ##iinncclluuddee <<lliibbeellff..hh>>
-
- EEllff **eellff__bbeeggiinn((iinntt ffiillddeess,, EEllff__CCmmdd ccmmdd,, EEllff **rreeff));;
-
- IIMMPPLLEEMMEENNTTAATTIIOONN
- IRIX systems
-
- DDEESSCCRRIIPPTTIIOONN
- eellff__bbeeggiinn, eellff__nneexxtt, eellff__rraanndd, and eellff__eenndd work together to process
- ELF object files, either individually or as members of archives.
- After obtaining an ELF descriptor from eellff__bbeeggiinn, the program may read
- an existing file, update an existing file, or create a new file.
- ffiillddeess is an open file descriptor that eellff__bbeeggiinn uses for reading or
- writing. The initial file offset [see llsseeeekk(2)] is unconstrained, and
- the resulting file offset is undefined.
-
- ccmmdd may have the following values:
-
- EELLFF__CC__NNUULLLL eellff__bbeeggiinn returns a null pointer, without opening a new
- descriptor. rreeff is ignored for this command. See
- eellff__nneexxtt(3E) and the EXAMPLES section for more
- information.
-
- EELLFF__CC__RREEAADD Specifies that the program examine the contents of an
- existing file. Depending on the value of rreeff, this
- command examines archive members or entire files. The
- following three cases may occur:
-
- 1. First, if rreeff is a null pointer, eellff__bbeeggiinn allocates
- a new ELF descriptor and prepares to process the
- entire file. If the file being read is an archive,
- eellff__bbeeggiinn also prepares the resulting descriptor to
- examine the initial archive member on the next call
- to eellff__bbeeggiinn, as if the program had used eellff__nneexxtt or
- eellff__rraanndd to ``move'' to the initial member.
-
- 2. Second, if rreeff is a non-null descriptor associated
- with an archive file, eellff__bbeeggiinn lets a program
- obtain a separate ELF descriptor associated with an
- individual member. The program should have used
- eellff__nneexxtt or eellff__rraanndd to position rreeff appropriately
- (except for the initial member, which eellff__bbeeggiinn
- prepares; see the example below). In this case,
- ffiillddeess should be the same file descriptor used for
- the parent archive.
-
- 3. Finally, if rreeff is a non-null ELF descriptor that is
- not an archive, eellff__bbeeggiinn increments the number of
- activations for the descriptor and returns rreeff,
- without allocating a new descriptor and without
- changing the descriptor's read/write permissions.
- To terminate the descriptor for rreeff, the program
- must call eellff__eenndd once for each activation. See
- eellff__nneexxtt(3E) and the EXAMPLES section for more
- information.
-
- EELLFF__CC__RREEAADD__MMMMAAPP
- This command duplicates the actions of EELLFF__CC__RREEAADD but
- uses the mmmmaapp() system call to access the file data in
- a more memory efficient manner. If, after lliibbeellff has
- opened the file, another process truncates the file
- lliibbeellff could get a Segmentation Violation attempting to
- read data it believes is in the file (but which is no
- longer there due to the truncation). Applications
- calling lliibbeellff with EELLFF__CC__RREEAADD__MMMMAAPP may therefore wish
- to install a signal handler for SSIIGGSSEEGGVV (Segmentation
- Violation) and issue a message when it happens.
-
- EELLFF__CC__RRDDWWRR This command duplicates the actions of EELLFF__CC__RREEAADD and
- additionally allows the program to update the file
- image [see eellff__uuppddaattee(3E)]. That is, using EELLFF__CC__RREEAADD
- gives a read-only view of the file, while EELLFF__CC__RRDDWWRR
- lets the program read and write the file. EELLFF__CC__RRDDWWRR
- is not valid for archive members. If rreeff is non-null,
- it must have been created with the EELLFF__CC__RRDDWWRR command.
-
- EELLFF__CC__WWRRIITTEE The program ignores previous file contents, presumably
- to create a new file. rreeff is ignored for this command.
-
- EELLFF__CC__WWRRIITTEE__FFAASSTT
- This command is the same as EELLFF__CC__WWRRIITTEE except that
- instead of performing mmaalllloocc() on memory for the output
- file [and then doing a wwrriittee(2) and ffrreeee()],
- EELLFF__CC__WWRRIITTEE__FFAASSTT writes the output directly to the file
- system (by doing a wwrriittee as needed). Avoiding running
- mmaalllloocc() can help limit time-consuming paging activity.
-
- eellff__bbeeggiinn Works on all files (including files with zero bytes),
- providing it can allocate memory for its internal structures and read
- any necessary information from the file. Programs reading object
- files thus may call eellff__kkiinndd or eellff__ggeetteehhddrr to determine the file type
- (only object files have an ELF header). If the file is an archive
- with no more members to process, or an error occurs, eellff__bbeeggiinn returns
- a null pointer. Otherwise, the return value is a non-null ELF
- descriptor.
-
- Before the first call to eellff__bbeeggiinn, a program must call eellff__vveerrssiioonn to
- coordinate versions.
-
- SSyysstteemm SSeerrvviicceess
- When processing a file, the library decides when to read or write the
- file, depending on the program's requests. Usually, the library
- assumes the file descriptor remains usable for the life of the ELF
- descriptor. If, however, a program must process many files
- simultaneously and the underlying operating system limits the number
- of open files, the program can use eellff__ccnnttll to let it reuse file
- descriptors. After calling eellff__ccnnttll with appropriate arguments, the
- program may close the file descriptor without interfering with the
- library.
-
- All data associated with an ELF descriptor remain allocated until
- eellff__eenndd terminates the descriptor's last activation. After the
- descriptors have been terminated, the storage is released; attempting
- to reference such data gives undefined behavior. Consequently, a
- program that deals with multiple input (or output) files must keep the
- ELF descriptors active until it finishes with them.
-
- EEXXAAMMPPLLEESS
- Example 1: The following is a prototype for reading a file. If the
- file is a simple object file, the program executes the loop one time,
- receiving a null descriptor in the second iteration. In this case,
- both eellff and aarrff will have the same value, the activation count will
- be two, and the program calls eellff__eenndd twice to terminate the
- descriptor. If the file is an archive, the loop processes each
- archive member in turn, ignoring those that are not object files.
-
- if (elf_version(EV_CURRENT) == EV_NONE)
- {
- /* library out of date */
- /* recover from error */
- }
- cmd = ELF_C_READ;
- arf = elf_begin(fildes, cmd, (Elf *)0);
- while ((elf = elf_begin(fildes, cmd, arf)) != 0)
- {
- if ((ehdr = elf32_getehdr(elf)) != 0)
- {
- /* process the file ... */
- }
- cmd = elf_next(elf);
- elf_end(elf);
- }
- elf_end(arf);
-
- Example 2: Alternatively, the next example illustrates random archive
- processing. After identifying the file as an archive, the program
- repeatedly processes archive members of interest. For clarity, this
- example omits error checking and ignores simple object files.
- Additionally, this fragment preserves the ELF descriptors for all
- archive members, because it does not call eellff__eenndd to terminate them.
-
- elf_version(EV_CURRENT);
- arf = elf_begin(fildes, ELF_C_READ, (Elf *)0);
- if (elf_kind(arf) != ELF_K_AR)
- {
- /* not an archive */
- }
- /* initial processing */
- /* set offset = ... for desired member header */
- while (elf_rand(arf, offset) == offset)
- {
- if ((elf = elf_begin(fildes, ELF_C_READ, arf)) == 0)
- break;
- if ((ehdr = elf32_getehdr(elf)) != 0)
- {
- /* process archive member ... */
- }
- /* set offset = ... for desired member header */
- }
-
- Example 3: The following outline shows how you might create a new ELF
- file. This example is simplified to show the overall flow.
-
- elf_version(EV_CURRENT);
- fildes = open("path/name", O_RDWR|O_TRUNC|O_CREAT, 0666);
- if ((elf = elf_begin(fildes, ELF_C_WRITE, (Elf *)0)) == 0)
- return;
- ehdr = elf32_newehdr(elf);
- phdr = elf32_newphdr(elf, count);
- scn = elf_newscn(elf);
- shdr = elf32_getshdr(scn);
- data = elf_newdata(scn);
- elf_update(elf, ELF_C_WRITE);
- elf_end(elf);
-
- Example 4: The following outline shows how you might update an
- existing ELF file. This example is simplified to show the overall
- flow.
-
- elf_version(EV_CURRENT);
- fildes = open("path/name", O_RDWR);
- elf = elf_begin(fildes, ELF_C_RDWR, (Elf *)0);
-
- /* add new or delete old information ... */
-
- close(creat("path/name", 0666));
- elf_update(elf, ELF_C_WRITE);
- elf_end(elf);
-
- In the previous example, the call to ccrreeaatt truncates the file, thus
- ensuring the resulting file will have the ``right'' size. Without
- truncation, the updated file might be as big as the original, even if
- information were deleted. The library truncates the file, if it can,
- with ffttrruunnccaattee [see ttrruunnccaattee(2)]. Some systems, however, do not
- support ffttrruunnccaattee, and the call to ccrreeaatt protects against this.
-
- Note that both file creation examples open the file with write and
- read permissions. The library is not compiled to use mmmmaapp so there is
- no need for write permission. But for maximum portability with
- implementations that do use mmmmaapp for file creation, you may want to
- provide both write and read permissions.
-
- NNOOTTEESS
- COFF is an object file format that preceded ELF. COFF object files
- cannot be used with this library.
-
- EELLFF__CC__RREEAADD__MMMMAAPP and EELLFF__CC__WWRRIITTEE__FFAASSTT are options specific to this
- implementation, not options that are generally available.
-
- SSEEEE AALLSSOO
- ccrreeaatt(2), llsseeeekk(2), mmmmaapp(2), ooppeenn(2), ttrruunnccaattee(2), eellff(3E),
- eellff__ccnnttll(3E), eellff__eenndd(3E), eellff__ggeettaarrhhddrr(3E), eellff__ggeettbbaassee(3E),
- eellff__ggeettddaattaa(3E), eellff__ggeetteehhddrr(3E), eellff__ggeettpphhddrr(3E), eellff__ggeettssccnn(3E),
- eellff__kkiinndd(3E), eellff__nneexxtt(3E), eellff__rraanndd(3E), eellff__rraawwffiillee(3E),
- eellff__uuppddaattee(3E), eellff__vveerrssiioonn(3E), aarr(4)
-
- This man page is available only online.
-